home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr35 / qprn102.zip / QWKPRUNE.DOC < prev    next >
Text File  |  1993-04-25  |  19KB  |  412 lines
  1.                                QWKPRUNE  1.02
  2.                                    -----
  3.   A utility to remove unwanted messages from QWK-format mail packets.
  4.  
  5.   QWKPRUNE.EXE, KILLMSG.EXE, ZIPPYZAP.EXE, SAVEQWK.EXE, MKPRN.EXE, this
  6.   documentation, and all associated documentation are Copyright (c) 1992,
  7.   1993, and GRABNUM.EXE is Copyright (c) 1993 by David Harden.  All rights
  8.   reserved.
  9.  
  10.   PARM.EXE is hereby released into the public domain.
  11.  
  12.   The code used to qualify filenames is based on QFN.C by Ray Duncan.
  13.   The original code was published in Vol. 7, No. 14 of PC Magazine, and is
  14.   copyrighted by Ziff-Davis.
  15.   
  16.   All brand or product names mentioned in this documentation or any
  17.   associated files are trademarks or registered trademarks of their
  18.   respective owners.  All products mentioned are copyrighted by their
  19.   respective owners.  My use of these trademarks does not imply that their
  20.   owners have endorsed QWKPRUNE, nor does it imply that I have endorsed
  21.   their products.
  22.  
  23.   QWKPRUNE should not be confused with QWKMerge, which is a trademark and
  24.   copyrighted product of Mike King.  QWKPRUNE and David Harden are not
  25.   affiliated with Mike King.
  26.  
  27.  
  28.                           Disclaimer of Liability
  29.                                    -----
  30.   There is no warranty of any kind, either express or implied, covering
  31.   this software or any associated materials.  This software and all
  32.   associated materials are provided as is, use them at your own risk.
  33.   The copyright holder is in no way responsible or liable for any losses or
  34.   damages of any kind that may result from the use of this software or any
  35.   associated materials, or from inability to use them.
  36.  
  37.  
  38.                             System requirements
  39.  
  40.   DOS 3.x or higher is preferred.  I see no reason why this program
  41.   shouldn't work with DOS 2.x, but this hasn't been tested.  Approximately
  42.   194K free RAM is needed to process a 400-message QWK. This includes a 64K
  43.   dynamically allocated buffer used to write the new MESSAGES.DAT to disk,
  44.   and 42K dynamic memory used to store data from the message headers.
  45.   Dynamic memory is allocated at runtime, so larger QWKs will take more
  46.   memory, and smaller ones will take less memory.  The write buffer won't
  47.   be allocated if the /T or /TQ are used. QWKPRUNE should be able to handle
  48.   any size QWK, as long as there is enough free RAM to store the message
  49.   data and enough free disk space to write the new MESSAGES.DAT.
  50.  
  51.  
  52.                               What does it do?
  53.                                    -----
  54.   Removes unwanted messages from QWK-format mail packets based on the
  55.   contents of their message headers.  The modified packet can either be
  56.   repacked or fed into a mail reader or other QWK utility.  See READER.DOC
  57.   for more details.
  58.  
  59.   An "unkill" option allows flexibility in deciding which messages are
  60.   pruned out.
  61.  
  62.   Removes (R), Re:, and Re : prefixes, as well as leading whitespace, from
  63.   the subject field of messages.
  64.   
  65.   Can tag messages for processing by programs such as KingQWK and QWKMerge.
  66.  
  67.   Transparently repairs conference numbers in packets from older doors that
  68.   pad the conference number with a space.
  69.  
  70.   "Untrashes" QWK packets altered by EZ-RDR.
  71.  
  72.  
  73.                              How to install it
  74.                                    -----
  75.   Place QWKPRUNE.EXE in a directory on your DOS path.  Use your editor
  76.   to create the needed control files (see below).  That's all.
  77.  
  78.  
  79.                                    Files
  80.                                    -----
  81.   QWKPRUNE's configuration and prune files are ASCII text files that may be
  82.   created and modified by any text editor, or by a word processor in
  83.   nondocument mode.  Lines may be up to 80 characters long.  If a line
  84.   begins with a semicolon, its contents will be ignored.
  85.  
  86.  
  87.                            The configuration file
  88.                                    -----
  89.   The configuration file is named QWKPRUNE.CFG, and is located in the same
  90.   directory as QWKPRUNE.EXE.  A configuration file may look something like
  91.   this:
  92.  
  93.   ZIP = pkzip
  94.   UNZIP = pkunzip
  95.   LHA = lha a /m
  96.   UNLHA = lha e
  97.   ARJ = arj a -e
  98.   UNARJ = arj e
  99.   ZOO = zoo -add %q *
  100.   UNZOO = zoo -extract %q *
  101.   USER_PACK = pkpak -a
  102.   USER_UNPACK = pkunpak
  103.   QWK = c:\download\qwk
  104.   WORK = c:\
  105.   PRUNE = c:\prune
  106.   GLOBAL = global.prn
  107.  
  108.   QWKPRUNE will automatically detect ZIP, LHA, ARJ, and ZOO files.
  109.   USER_PACK and USER_UNPACK are commands to pack and unpack files
  110.   compressed with another archiver.  In these entries, %q may be used as
  111.   a substitute for the QWK file name.
  112.  
  113.   QWK is the directory where you want QWKPRUNE to look for QWK files.  WORK
  114.   is the directory where QWKPRUNE will create its work directory.  A
  115.   directory named QP$WORK will be created under this directory.  PRUNE is
  116.   the default directory where prune files are located.  GLOBAL is the name
  117.   of a global prune file, which will be used for all QWK packets.  If
  118.   GLOBAL is not specified, a global prune file will not be used.
  119.  
  120.   A packer and unpacker for at least one archive type must be specified.
  121.   If QWK or WORK is left unspecified, the current working directory will be
  122.   used for that option.  If PRUNE is not specified, it's assumed that prune
  123.   files are located in the same directory as QWKPRUNE.EXE.  Options may
  124.   appear in any order, and case is not significant.  If a line is not a
  125.   valid option, it should be ignored.
  126.  
  127.   If the work directory exists and is empty, QWKPRUNE will use it without
  128.   comment.  If it isn't empty, you'll be asked if you want to abort the
  129.   program or delete all the files in the work directory.
  130.  
  131.   If you use a batch file to call the packer or unpacker, place COMMAND /C
  132.   in front of the batch file's name, or use PARM.EXE.
  133.  
  134.   A sample configuration file is included in the distribution archive.
  135.  
  136.  
  137.                                 Prune files
  138.                                    -----
  139.   Prune files control which messages will be removed from the QWK packet.
  140.   By default, they are named BBSID.PRN, and are located in the same
  141.   directory as QWKPRUNE.EXE.  For example, if a BBS creates packets named
  142.   ABC.QWK, the default prune file name for that board is ABC.PRN.  QWKPRUNE
  143.   takes the BBSID from CONTROL.DAT, so it doesn't matter what the QWK
  144.   packet is named on disk.  A line should have the following format: 
  145.   [!]conference number,switch[option]:text.  At present, there can only be
  146.   one conference number per line.  A prune file may have up to 75 entries,
  147.   minus the number of entries in the global prune file.
  148.  
  149.   The conference number is the conference to prune messages from, and must
  150.   be followed by a comma or semicolon.  Switch values are F,T,B,S,D,N, and
  151.   A.  Option may be either P or B, or it may be omitted.  If an invalid
  152.   option is used, it will be ignored.  The switch (or option, if used) must
  153.   be followed by a colon or tilde (~).  Text is the text to search for.
  154.   Case is not significant, and invalid lines should be ignored.
  155.  
  156.   To search the entire packet, enter an 'A' as the conference number.
  157.   If this option is used with the N switch, the line will be ignored.
  158.  
  159.   F: assumes that "text" is a user name, and will delete all messages from
  160.   that user.  T: works similarly, except that it kills messages to a user.
  161.   B: finds messages that are both from and to a user.  If "text" is @ME@,
  162.   it'll be replaced with your user name from CONTROL.DAT.
  163.  
  164.   S: prunes out all messages that have "text" as their subject line.
  165.  
  166.   If any of these switches are followed by P, all messages that contain
  167.   "text" within the appropriate field(s) will be removed.
  168.  
  169.   If the S switch is followed by a B, all messages whose subject line
  170.   begins with "text" will be deleted.
  171.  
  172.   D: treats "text" as a number of days before the current date.  Messages
  173.   older than that will be removed from the packet.
  174.  
  175.   N: assumes that "text" is a message number, and deletes that message.
  176.  
  177.   A: prunes out all messages within a conference.  Anything following the
  178.   'A' will be ignored.
  179.  
  180.   If a line begins with an exclamation point, messages meeting the search
  181.   specification will be "unkilled".  This allows you to do things such as
  182.   killing all messages in a conference, then unkilling those you want to
  183.   keep.  For example:
  184.                                    10,A:
  185.                                    !10,N:100
  186.                                    !10,SP:Interesting subject
  187.                                    A,B:Joe Schmuck
  188.                                    A,D:30
  189.  
  190.   will kill all messages in conference 10, except for message number 100
  191.   and all messages with "interesting subject" in their subject fields.  It
  192.   will then kill all messages either to or from "Joe Schmuck".  Finally, it
  193.   will delete all messages more than 30 days old.
  194.  
  195.   If the switch (or option, if used) is followed by a tilde (~), all
  196.   messages in the conference that do not meet the search specification will
  197.   be removed.  This has the same effect as killing all messages in a
  198.   conference, then unkilling those that meet the search specification.
  199.   In the example above, the first two lines could be replaced by
  200.   10,N~100.  This also works with the D switch.  For example, A,D~30 will
  201.   delete all messages that are 30 or less days old.  Of course, it'll also
  202.   work with the unkill option.
  203.  
  204.   You can define a global prune file in the configuration file.  This file
  205.   may contain up to 25 entries, and will be used with all QWK packets.  It
  206.   acts like a normal prune file, except that the N: switch and conference
  207.   numbers other than 'A' or 0 are invalid within it.  When scanning a QWK
  208.   packet, entries in the global prune file will be processed before those
  209.   in the regular prune file.
  210.  
  211.  
  212.                             Command line syntax
  213.                                    -----
  214.   The command line syntax is:
  215.     QWKPRUNE [d:][dir][QWK_file] [d:][dir][prune_file] [options]
  216.  
  217.   If you give a drive and/or directory with the prune file, QWKPRUNE will
  218.   still look for the global prune file in the default prune directory
  219.   specified in QWKPRUNE.CFG.
  220.  
  221.   DOS wildcards (* and ?) may be used in the QWK file name.
  222.  
  223.   If no extension is given, .QW* will be appended to the QWK file name,
  224.   and .PRN will be appended to the prune file name.
  225.  
  226.   The QWK and prune directories can be specified on the command line by
  227.   ending the appropriate entry with a colon, backslash, or period.
  228.   This will override the QWK and/or PRUNE entries in the configuration
  229.   file.
  230.  
  231.   If you wish to specify the prune file or prune directory, you must
  232.   enter something for the QWK file, unless you're using the /M option.
  233.  
  234.   The options are:
  235.  
  236.   /M[d:][dir] -  If this switch is set, QWKPRUNE assumes that the QWK file
  237.   has already been unpacked. If a drive and/or directory is given, it'll
  238.   look there for it, otherwise the current directory will be used.  It will
  239.   not create its work directory or repack the QWK file.  Note: When using
  240.   this option, only give the name of the prune file on the command line.
  241.   When giving a drive and/or directory, there must not be a space between
  242.   the M and the drive/directory.  Use this switch if you want to feed the
  243.   output to a mail reader.
  244.  
  245.   /B -  "Batch" mode.  If this switch is set, the work directory won't be
  246.   removed.
  247.  
  248.   /C[d:][dir]filename.ext -  This option lets you use a configuration file
  249.   other than the default QWKPRUNE.CFG.  There must not be a space between
  250.   the C and the filename to use.
  251.  
  252.   /T -  Use this switch to tag messages to be deleted later.
  253.  
  254.   /TQ - Use this option to tag messages for processing by KingQWK and
  255.   QWKMerge.  /T and /TQ will be ignored if /N has appeared earlier in the
  256.   command line.
  257.  
  258.   /N -  Use this option if you don't want to use a prune file.  Messages
  259.   that have been tagged for deletion by KingQWK, KILLMSG, ZIPPYZAP, or
  260.   QWKPRUNE /T will still be pruned out.  Also, (R), Re:, and Re : prefixes
  261.   and leading whitespace will still be stripped from the subject lines.
  262.   This will be ignored if either /T or /TQ appeared earlier in the command
  263.   line.
  264.  
  265.   /NG - If a global prune file is defined, this switch keeps it from being
  266.   used.  Regular prune files will still be used.
  267.  
  268.   /Dnn - If wildcards are used in the QWK file name, or the default (*.QW*)
  269.          is used, packets older than nn days will not be pruned.  There
  270.          must not be a space between the D and the number.
  271.  
  272.  
  273.                           Things to watch out for
  274.                                    -----
  275.   QWKPRUNE hasn't been tested with DOS 2.x, but I see no reason why it
  276.   shouldn't work.  QWKPRUNE.EXE won't be able to find itself under DOS 2.x,
  277.   so it'll assume that its configuration file and prune files are in the
  278.   current directory.
  279.  
  280.   If your mail reader keeps "bookmarks", you may want to mark packets as
  281.   unread after pruning them.  Otherwise, they'll no longer be accurate.  If
  282.   your reader can't mark packets as unread, you can manually delete the
  283.   "bookmarks".  QWKPRUNE will delete bookmarks from EZ-RDR, KingQWK,
  284.   DeLuxe², Session Manager, and Blue Wave if any messages are pruned out.
  285.  
  286.   Don't use the /M option on a QWK while you're reading it, unless you're
  287.   also using the /T option.  Some readers may leave MESSAGES.DAT open while
  288.   running outside programs.  Rewriting MESSAGES.DAT under such conditions
  289.   may garble the file.  Even if your reader closes MESSAGES.DAT, it may not
  290.   reload the changed .NDX files generated by QWKPRUNE.
  291.  
  292.   Users on networks or using multitaskers should be sure that the QWK file
  293.   isn't being read or modified by any other process while it's being
  294.   pruned.
  295.  
  296.   If there are Net Status blocks at the end of MESSAGES.DAT, these blocks
  297.   will not be copied to the rebuilt MESSAGES.DAT.  
  298.  
  299.  
  300.                                Error Messages
  301.                                    -----
  302.   Prune file(s) empty:
  303.          Neither the regular prune file nor the global prune file (if
  304.          defined) contained any valid entries.  (R), Re:, and Re : prefixes
  305.          and leading whitespace were still stripped from the subject lines.
  306.  
  307.   No messages pruned:
  308.          No messages were found to prune.
  309.  
  310.   Not enough memory to store all records:
  311.          A check of the far heap didn't find enough memory to store all
  312.          the message headers.
  313.  
  314.   Memory allocation error:
  315.          An error occurred when allocating dynamic memory.  Probably caused
  316.          by attempting to allocate more memory than was available.  Since
  317.          QWKPRUNE checks to see how much far memory is available before
  318.          allocating any, this shouldn't happen.  Please let me know if it
  319.          does.
  320.  
  321.   Unable to open config file:
  322.          QWKPRUNE was unable to open its configuration file.
  323.  
  324.   Unsupported archive type:
  325.          Either a packer or unpacker wasn't defined for the archive type of
  326.          the QWK file.
  327.  
  328.   Unable to locate QWK file:
  329.          The QWK packet could not be found.
  330.  
  331.   Unable to open CONTROL.DAT:
  332.          QWKPRUNE was unable to open the CONTROL.DAT file from the mail
  333.          packet.  If this error occurs, the mail packet is probably not a
  334.          QWK packet.  If the packet was compressed with LHA or ZOO, it 
  335.          also may indicate that there wasn't enough disk space to unpack
  336.          CONTROL.DAT.  If a batch file was used to call the unpacker, there
  337.          may not have been enough free memory to unpack it.
  338.  
  339.   Error in CONTROL.DAT:
  340.          An error occurred when reading CONTROL.DAT.  Either it's garbled,
  341.          or it isn't from a QWK file.
  342.  
  343.   Unable to open MESSAGES.DAT:
  344.          QWKPRUNE was unable to open the MESSAGES.DAT file from the QWK
  345.          packet.  If the packet was compressed with LHA or ZOO, this may
  346.          indicate that there wasn't enough disk space to unpack it.  If you
  347.          used a batch file to call the unpacker, it may also indicate there
  348.          wasn't enough free memory to unpack it.
  349.  
  350.   No .NDX files found:
  351.          QWKPRUNE was unable to locate the .NDX files from the mail packet.
  352.          Either the mail packet isn't a QWK, or the mail door didn't create
  353.          .NDX files, or there are no messages in the packet.  If the QWK
  354.          door that produced the packet was configured not to create .NDX
  355.          files, you'll need to rebuild them before pruning the packet.
  356.  
  357.   [QWK/prune/work] directory not found:
  358.          The QWK, prune, or work directory does not exist.
  359.  
  360.                               DOS error levels
  361.                                     ----
  362. 4:  Not enough memory to store all records.
  363. 5:  Unsupported archive type.
  364. 6:  Unable to open CONTROL.DAT.
  365. 7:  Error in CONTROL.DAT.
  366. 8:  Unable to open MESSAGES.DAT.
  367. 9:  No .NDX files found.
  368. 10: An error occurred when unpacking the QWK file.
  369. 11: File write error due to lack of disk space.
  370. 12: Invalid command line option.
  371. 13: Unable to locate QWK file.
  372. 14: Error changing to the drive the work directory is on.
  373.     Error changing to the work directory.
  374. 15: An error occurred when attempting to spawn a program.
  375. 16: An error occurred when repacking the QWK file.
  376. 17: File open error.
  377. 18: File write error.
  378. 19: Memory allocation error.
  379. 20: Unable to open config file.
  380. 21: The work, QWK, or prune directory does not exist.
  381. 22: Control-break exit.
  382. 23: The program was aborted by the user because the work directory wasn't
  383.     empty.
  384.  
  385.  
  386.                               Acknowledgements
  387.                                    -----
  388.   Thanks to Mark May and Patrick Lee for gathering and distributing
  389.   information on the QWK specification, and to all those they collected
  390.   this data from.
  391.  
  392.   Thanks also to Joe and Pat McNeal, Diane Merriam, Bill Peek, and Darrell
  393.   Kitchen.
  394.  
  395.  
  396.                               How to reach me
  397.                                    -----
  398.   Please send comments, suggestions, bug reports, etc. to me at:
  399.  
  400.   RIME Shareware or Offline conference.  R/O capable at site ->1066
  401.   RIME Common conference.                Routed R/O ONLY at site ->1066
  402.   Ilink Shareware or Offline conference.
  403.   Fido netmail    1:2320/110
  404.   CompuServe mail 73760,2217 or >INTERNET:david.harden@tfd.coplex.com
  405.   Internet Email  david.harden@tfd.coplex.com
  406.  
  407.   Or send mail to:
  408.  
  409.   David Harden
  410.   P.O. Box 197086
  411.   Louisville, KY 40259
  412.